package com.zenithmind.classroom.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.classroom.pojo.dto.ProgressUpdateDTO;
import com.zenithmind.classroom.pojo.domain.LearningProgress;
import com.zenithmind.classroom.pojo.vo.LearningAnalysisVO;
import com.zenithmind.classroom.pojo.vo.LearningProgressVO;
import com.zenithmind.classroom.pojo.vo.LearningStatisticsVO;

import java.time.LocalDateTime;
import java.util.List;

/**
 * 学习进度服务接口
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
public interface LearningProgressService extends IService<LearningProgress> {

    /**
     * 更新学习进度
     * 
     * @param updateDTO 更新DTO
     * @return 是否成功
     */
    Boolean updateProgress(ProgressUpdateDTO updateDTO);

    /**
     * 开始学习
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @param chapterId 章节ID
     * @param lessonId 课时ID
     * @return 是否成功
     */
    Boolean startLearning(String userId, String courseId, String chapterId, String lessonId);

    /**
     * 完成学习
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @param chapterId 章节ID
     * @param lessonId 课时ID
     * @return 是否成功
     */
    Boolean completeLearning(String userId, String courseId, String chapterId, String lessonId);

    /**
     * 暂停学习
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @param chapterId 章节ID
     * @param lessonId 课时ID
     * @return 是否成功
     */
    Boolean pauseLearning(String userId, String courseId, String chapterId, String lessonId);

    /**
     * 获取用户课程进度
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @return 学习进度
     */
    LearningProgressVO getUserCourseProgress(String userId, String courseId);

    /**
     * 获取用户章节进度
     * 
     * @param userId 用户ID
     * @param chapterId 章节ID
     * @return 学习进度
     */
    LearningProgressVO getUserChapterProgress(String userId, String chapterId);

    /**
     * 获取用户课时进度
     * 
     * @param userId 用户ID
     * @param lessonId 课时ID
     * @return 学习进度
     */
    LearningProgressVO getUserLessonProgress(String userId, String lessonId);

    /**
     * 获取用户学习统计
     * 
     * @param userId 用户ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 学习统计
     */
    LearningStatisticsVO getUserLearningStatistics(String userId, LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获取课程学习统计
     * 
     * @param courseId 课程ID
     * @return 学习统计
     */
    LearningStatisticsVO getCourseLearningStatistics(String courseId);

    /**
     * 获取用户学习分析
     * 
     * @param userId 用户ID
     * @param days 分析天数
     * @return 学习分析
     */
    LearningAnalysisVO getUserLearningAnalysis(String userId, Integer days);

    /**
     * 获取学习排行榜
     * 
     * @param courseId 课程ID
     * @param type 排行类型（1-学习时长，2-完成进度，3-学习质量）
     * @param limit 限制数量
     * @return 排行榜
     */
    List<LearningProgressVO> getLearningRanking(String courseId, Integer type, Integer limit);

    /**
     * 获取学习建议
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @return 学习建议
     */
    List<String> getLearningRecommendations(String userId, String courseId);

    /**
     * 记录学习行为
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @param lessonId 课时ID
     * @param action 行为类型
     * @param duration 持续时间
     * @param deviceType 设备类型
     * @return 是否成功
     */
    Boolean recordLearningBehavior(String userId, String courseId, String lessonId, 
                                  String action, Integer duration, Integer deviceType);

    /**
     * 获取学习路径
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @return 学习路径
     */
    List<LearningProgressVO> getLearningPath(String userId, String courseId);

    /**
     * 预测学习完成时间
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @return 预计完成时间
     */
    LocalDateTime predictCompletionTime(String userId, String courseId);

    /**
     * 获取学习热力图
     * 
     * @param userId 用户ID
     * @param year 年份
     * @return 热力图数据
     */
    List<LearningAnalysisVO.HeatmapData> getLearningHeatmap(String userId, Integer year);

    /**
     * 同步学习进度
     * 
     * @param userId 用户ID
     * @param deviceType 设备类型
     * @return 是否成功
     */
    Boolean syncLearningProgress(String userId, Integer deviceType);

    /**
     * 导出学习报告
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @param format 导出格式
     * @return 报告文件路径
     */
    String exportLearningReport(String userId, String courseId, String format);

    /**
     * 重置学习进度
     * 
     * @param userId 用户ID
     * @param courseId 课程ID
     * @return 是否成功
     */
    Boolean resetLearningProgress(String userId, String courseId);

    /**
     * 获取学习提醒
     * 
     * @param userId 用户ID
     * @return 提醒列表
     */
    List<String> getLearningReminders(String userId);
}
